Blazin' Forth supports all the necessary words to handle any peripheral device on the serial bus, or on the IEEE bus, if you have an extension card like the BUSCARD II. I left certain definitions out deliberately, so that users who require them can define them as they like.
Higher Level Words.
The system supports I/O redirection of output to a printer. The words PRINTER and NOPRINTER will open a channel to a 1526 printer, connected as device # 4. After executing PRINTER , all output will be directed to the printer. NOPRINTER will redirect output to the screen. Both PRINTER and NOPRINTER are DEFERed (see DEFER for more information), to make it easy for you to alter them, if you need to, without having to recompile the system. #LP is a constant which contains the current device number of the systems line printer. As currently configured, PRINTER sends a control code to the printer which turns on paging, and NOPRINTER sends a control code which turns paging off (these codes are for the 1526 printer). If your printer uses different control codes, or doesn't require them, you will probably want to revector these words. I would suggest you examine the definitions of LP and NLP for an example of how to write such words in Forth. In particular, it is important to have PRINTER set the user variable PRINTING? to TRUE, and NOPRINTER should reset PRINTING? to false.
The word DOS" has been provided to allow you to send commands to the disk drive from Forth. Any command which is recognized by the 1541 or a compatible drive may be sent using this word. As an example:
DOS" N0:DISKNAME,ID"
will format a disk in drive 0. Note that there must be a space between the " and the command.
To read the disks error channel, you can use the word ?DISC . Note that ?DISC will only display the message if there is an error.
MOUNT
MOUNT initializes the virtual disk operating system of Forth. It *must* be used before any word which accesses the disk. Note that you only need to use this word once, at the start of a session, and not before every LIST or LOAD command. (You must reissue it if you use RESTART, or if you change disks during a session.) Note that the disk light will remain on while the system is in operation. This is normal, and should not cause you a second thought.
If you require information on accessing standard CBM disk files, please see the appendix. These are the only words required in normal usage of the system.
*fp0
*cn1;Extensions to the 83 Standard*cn0
BOOLEANS:
Blazin' Forth contains the following boolean tests which are not part of the 83 standard:
0<> Leaves a true flag if top of stack is non-zero.
0> Leaves a true flag if top of stack is positive.
<> Leaves a true flag if top of stack is not equal to second element of stack.
D> Leaves a true flag if the second double number is greater than the doublenumber on the top of the stack.
CONDITIONAL EXECUTION
BEGIN...AGAIN is included. It is the same as
BEGIN .... FALSE UNTIL
Or, in other words, an infinite loop.
Multiple WHILEs are supported by Blazin' Forth. For example:
BEGIN <action> <condition> WHILE <action> <condition> WHILE <action> REPEAT
Note that you are not limited to only two whiles, this is simply an example.
LOOPING
Forth-83 loops are very fast, make the older /LOOP unnecessary, and are generally much improved over the earlier Forth Loops. However, when the loop index is equal to the loop limit, the loop will not execute once, but 64k times. For occasions when this is not wanted, Blazin' Forth provides ?DO . ?DO will not allow the loop to be executed if the limit and index are equal. For example:
: LOOP1 ?DO I . LOOP ;
Does the same thing as:
: LOOP2 2DUP <> IF DO I . LOOP ELSE 2DROP THEN ;
Note that the first is much shorter, and also much faster. Of course, ?DO will also work with +LOOP, just like DO does.
Forth-83's LEAVE is also changed from earlier LEAVEs. Forth-83's LEAVE jumps immediately to the word after LOOP or +LOOP, while the older LEAVE would continue through the remainder of the loop, exiting at the LOOP or +LOOP. Blazin' Forth contains a word, ?LEAVE which can be quicker and a real code saver when all you need to do is scram. For example:
: EXIT1 10 0 DO I . 5 = ?LEAVE LOOP ;
Will cause the same effect as:
: EXIT2 10 0 DO I . 5 = IF LEAVE THEN LOOP ;
Note that ?LEAVE takes less room, and is also quicker, than the second alternative.
Interactive Extensions
?KEY ( -- char )
This word works just like the standard KEY , but while KEY will wait for a keypress, ?KEY reads the keyboard, and returns the ASCII value of the key pressed, or a null (0) if no key was pressed.
PAUSE ( -- flag)
This word is basically a souped up ?TERMINAL. ?TERMINAL will return a TRUE flag if the stop key is pressed, and false otherwise. PAUSE will do the same thing, but, additionally, if any key other than the stop key has been pressed, it will halt execution and wait for the next key. Note that although PAUSE handles the waiting, it is up to the calling word to process the flag.
JOYSTICK ( port# -- direction )
Requires a value on the stack, which should be either 0 or 1. If 0, joystick port 1 will be read, If 1, joystick port 2 will be read. Joystick leaves a value on the top of the stack which indicates the direction of the joystick. -1 means the stick is centered, 0 is up, with values increasing to the right, so 1 is forward and up, 2 is to the right, etc. Note that if these values are multiplied by 45 the result is suitable for SETH (see graphics extensions).
JOYBUTTON ( port# -- flag )
Leaves true on the stack if the joy stick button at the appropriate port is depressed, otherwise leaves false. Requires the same values on the stack as JOYSTICK.
PADDLE ( paddle# -- value )
Requires a number from 0 to 3 on the stack which specifies the paddle. Leaves a value between 0 and 255 on the stack, depending on the setting of the appropriate paddle. Note that these words may also be used to read other devices, such as a Koala Pad.
PADDLEBUTTON ( paddle# -- flag)
Leaves a true or a false on the stack, depending on whether or not the addressed button has been depressed. Requires the same values as PADDLE.
JIFFY! ( doublenumber -- )
Used to set the 64's Jiffy Clock. Requires a double number on the stack.
JIFFY@ ( -- doublenumber )
Used to read the 64's Jiffy Clock. Leaves a double number on the stack. Note that 1 Jiffy = 1/60 of a second.
JIFFIES ( n -- )
Requires a single number on the stack. JIFFIES will cause a wait of n jiffies before continuing.
CURSOR ( x y -- )
Positions the cursor at the x y coordinates on the top of the stack.
CURSORPOS ( -- x y )
Leaves the current position of the cursor ( x and y ) on the top of the stack.
CONSTANTS
Blazin' Forth has precompiled the following constants.
0 1 2 3
These simply leave their value on the stack.
TRUE
Leaves the value for TRUE (-1) on the stack.
FALSE
Leaves the value for FALSE (0) on the stack.
VARIABLES
Blazin' Forth has the following variables which may be of use to you:
#LINE
A user variable which contains the number of times the word CR has been executed. May be examined to control output formatting. Note that this word is reset by PAGE to 0.
#OUT
A user variable which contains the number of characters TYPEd or EMITted since the last CR. Note that words such as SPACE or SPACES, which use EMIT, will also bump this variable. May be examined by the user to control output formatting. CR resets to 0.
DPL
A user variable which contains the number of places after the decimal point for input conversion.
FENCE
A user variable which contains the address below which FORGET will not operate. This may be changed by the user, but caution must be observed.
VIEW?
A user variable which controls whether or not a view field will be compiled by CREATE. The view field is the field used by LOCATE to find the source code for definitions in the dictionary. If VIEW? is 0 , then no view field will be compiled. To compile view fields, VIEW? must contain a 2. Any other value will cause the system to behave oddly. Note that turning VIEW? off will save memory, but it does not affect execution speed. You should also be aware that executing SAVE-FORTH will save the current values of certain system variables, such as FENCE, VIEW?, WIDTH and WARNING.
WARNING
A variable which controls the printing of non-fatal error messages (such as NAME ALREADY EXISTS). If warning is false, no messages will be printed.
WIDTH
Controls the number of characters actually stored in the dictionary. The default is 31, which is specified by the Forth-83 standard. This may be changed by the user. Note that using fewer characters will save memory.
Although not variables, the following are used so often, this is probably a good place to tell you about them:
OFF
Stores a false (0) in a variable. VARIABLENAME OFF is the same as FALSE VARIABLENAME ! , but much quicker.
ON
Stores a true (-1) in a variable. VARIABLENAME ON is the same as TRUE VARIABLENAME ! , but much quicker.
MATH
(Note: The stack notation below uses n as an abbreviation for single numbers, and d to represent double numbers. Also note that floored division is used, to be consistant with the rest of the standard)
2* ( n -- 2*n)
Performs an arithmetic left shift of n, leaving the result on the top of the stack.
D2* ( d -- d*2)
Same as 2* , but for double numbers.
M* ( n1 n2 -- d )
D is the doublenumber product of the single numbers n1 n2.
M*/ ( d1 n1 n2 -- d2 )
d2 is the result of multiplying d1 by n1 and dividing the resulting product by n2. An triple-precision intermediate product is used, and all values are signed.
M+ ( d1 n -- d2 )
d2 is the sum of d1 and n. All values are signed.
M/ ( d1 n -- n2 n3)
n3 is the remainder and n2 is the quotient of the division of d by n1. All values are signed.
M/MOD ( ud1 u1 -- u2 ud2 )
ud2 is the quotient and u2 is the remainder of the division of ud1 by u1.
S>D ( n -- d )
n is sign extended to form the double number d.
MISC:
ASCII
A handy word. Used in the form
ASCII *
to either leave the ascii code for the following character on the top of the stack, or compile it as a literal for later execution. ASCII makes programs much more readable, and also saves much time spent looking up ascii codes in tables.
*fp0
CONTROL
Also handy. Used in the form
CONTROL "c"
where c is one of the 64's weird reversed control characters, such as a cursor left or a clear screen.
FREE ( -- #bytes)
Leaves the number of bytes free on the stack. This may be changed by CONFIGURE. (Note that the amount of memory occupied by the disk buffers is not considered FREE, although it may be used by user programs if no disk accesses are to be performed.)
//
Causes the rest of the line to be viewed as a comment. Corresponds to a backslash, found on some computers, but, regrettably, not on the C64.
Blazin' Forth also includes Kim Harris's experimental proposals for dictionary operators. See the text of the Forth-83 standard for more information.
